Pennyless - Bank Account Verification API

The following document highlights the details of the Pennyless API:

Objective

The Pennyless Verification API validates a bank account number and the Indian Financial System Code(IFSC) associated with it using a pennyless verification mechanism.

note

The complete list of all banks supported by the Pennyless API can be found under the List of Supported Banks section on this page.

Input	Output
The account number and the Indian Financial System Code(IFSC)	Confirmation if the account exists,the name of the user associated with the account, and whether the account is an overseas account*

did you know

An *Overseas Account bank account is one held in a country different from your place of residence. These accounts can be beneficial for managing international finances, investments, and personal or business needs. For residents of India, opening an offshore account requires adherence to rules outlined by the Reserve Bank of India (RBI).

API URL

https://ind-engine.thomas.hyperverge.co/v1/pennyless

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the fields required for the API's request body.

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
accountNumber	Mandatory	The account number which you want to verify	Not Applicable	Not Applicable
ifsc	Mandatory	The IFSC value associated with the account's branch	Not Applicable	Not Applicable
accountType	Optional	This flag enables the isOverseasAccount check. When included in the request, the API response indicates whether the bank account is classified as overseas or non-overseas	"yes" or "no"	Not Applicable
strictValidation	Optional	This parameter triggers a failure response for Blocked and Overseas accounts if the account name cannot be retrieved. Refer to the Error Responses section for a complete overview of the responses returned; when this parameter is enabled in the request.	"yes" or "no"	Not Applicable

Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/pennyless' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "accountNumber": "<Enter_the_Account_Number>",
    "ifsc": "<Enter_the_IFSC_Value>",
    "accountType": "<Enter_yes_or_no>",
    "strictValidation": "<Enter_yes_or_no>"
}'

Success Responses

The following are success responses from the API:

Successful Verification

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "accountExists": true,
    "accountName": "<Name_of_the_Registered_User>"
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Overseas Account

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "accountExists": true,
    "accountName": "<Name_of_the_Registered_User>",
    "isOverseasAccount": "Yes" // returned when accountType is enabled in the request 
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Non-Overseas Account

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "accountExists": true,
    "accountName": "<Name_of_the_Registered_User>",
    "isOverseasAccount": "No" // returned when accountType is enabled in the request 
  },
  "metaData": {
    "requestId": "<Request_Identifier>"
  }
}

Success Response Details

The following table provides the details of the fields in a success response.

Parameter	Type	Description
accountExists	boolean	Returns "true" if the account exists, "false" otherwise
accountName	string	The name of the user associated with the bank account
isOverseasAccount	string	Returns "Yes" if the bank account is an overseas account, and "No" otherwise. This parameter is included in the API response only when the accountType flag is enabled request.

Failure Response

The following is a failure response when the account in the request does not exist.

{
  "statusCode": 200,
  "status": "failure",
  "error": "Account does not exist"
}

Error Responses

The following are some error responses from the API:

Input Validation Error - Invalid IFSC Code

{
    "statusCode": 400,
    "status": "failure",
    "error": "Invalid account number or ifsc provided",
    "metaData": {
        "requestId": "<Request_ID>"
    }
}

Missing or Invalid with Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Invalid IFSC

{
  "status": "failure",
  "statusCode": 422,
  "error": "Invalid IFSC Pattern"
}

IFSC Not Supported

{
  "statusCode": 422,
  "status": "failure",
  "error": "IFSC not supported"
}

No accountName: Overseas Account

The following response is returned when the accountName cannot be retrieved for an Overseas account:

{
  "status": "failure",
  "statusCode": "422",
  "error": "Given account is an NRE account" // NRE, which stands for Non-Resident External, denotes the Overseas accounts
}

No accountName: Blocked Account

The following response is returned when the accountName cannot be retrieved for a Blocked account:

{
  "status": "failure",
  "statusCode": "422",
  "error": "Account is blocked"
}

Beneficiary Bank Offline

{
  "statusCode": 424,
   "status": "failure",
   "error": "Beneficiary Bank Offline"
}

Verification Request Failure

{
    "statusCode": 424,
    "status": "failure",
   "error": "Unable to validate request"
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "error": "Internal Server Error"
}

Source Bank Declined

{
  "statusCode": 500,
  "status": "failure",
  "error": "Source Bank declined"
}

Request Timeout

{
  "statusCode": 504,
  "status": "failure",
  "error": "Request timeout"
}

Bank Not Supported

{
  "statusCode": 522,
  "status": "failure",
  "error": "Verification service for requested bank is not supported"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all the error responses:

Status Code	Error Message	Error Description
400	Input Validation Error	The IFSC value in the request does not match its mandatory requirement of nine characters
401	Missing/Invalid Credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
422	Invalid IFSC Pattern	The provided IFSC code does not match the expected format
422	IFSC Not Supported	The provided IFSC code is not supported by the system
422	Given account is an NRE account	The accountNameparameter — which provides the name of the user associated with the bank account — cannot be retrieved for an Overseas account. Only returned when the strictValidation parameter is enabled in the request
422	Account is blocked	The accountNameparameter — which provides the name of the user associated with the bank account — cannot be retrieved for a Blocked account. Only returned when the strictValidation parameter is enabled in the request
424	Beneficiary Bank Offline	The user's bank account has been blocked due to inactivity
424	Unable to Validate Request	The system is unable to process a bank account verification request
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
500	Source Bank Declined	The source bank declined the request due to internal constraints
504	Request Timeout	The server timed out while waiting for a response
522	Bank Not Supported	Verification service for the requested bank is not supported

List of Supported Banks

The following is a list of all banks supported by the Pennyless API.

Banks	IFSC Code (first 4 digits)
Kotak Mahindra	KKBK
Axis bank	UTIB
SURYODAY SMALL FINANCE BANK LIMITED	SURY
SBI Bank	SBIN
IDBI BANK	IBKL
YES BANK	YESB
CORPORATION BANK	CORP
ALLAHABAD BANK	ALLA
PAYTM PAYMENTS BANK LTD	PYTM
CITI BANK	CITI
DEVELOPMENT BANK OF SINGAPORE	DBSS
INDIA POST PAYMENT BANK	IPOS
ANDHRA BANK	ANDB
INDUSIND BANK	INDB
BANK OF MAHARASHTRA	MAHB
FEDERAL BANK	FDRL
NSDL Payments Bank	NSPB
Jana Small Finance Bank	JSFB
Union Bank	UBIN
Canara Bank	CNRB
Indian Bank	IDIB
South Indian Bank	SIBL
Standard Chartered Bank	SCBL
Karnataka Bank	KARB
UCO Bank	UCBA
TJSB Bank	TJSB
Cosmos Cooperative Bank	COSB
RAJKOT NAGARIK SAHAKARI BANK LTD	RNSB
Bank of Baroda	BARB
Bank of India	BKID
Saraswat Co-operative Bank	SRCB
Punjab and Sind Bank	PSIB
Tamilnad Mercantile Bank LTD	TMBL
City Union Bank	CIUB
CATHOLIC SYRIAN BANK LTD	CSBK
AU Small Finance Bank	AUBL
The Shamrao vithal Co-operative Bank	SVCB
Abhyudaya Co-op Bank	ABHY
Dhanalaxmi Bank	DLXB
The Ratnakar Bank Limited	RATN
THE JAMMU AND KASHMIR BANK LTD	JAKA
Janta Sahakari Bank	JSBP
PRAGATHI KRISHNA GRAMIN BANK	PKGB
THE KALUPUR COMMERCIAL CO. OP. BANK LTD.	KCCB
PARSIK JANATA SAHAKARI BANK LTD	PJSB
Equitas Small Finance Bank	ESFB
DEOGIRI NAGARI SAHAKARI BANK LTD.	DEOB
Ambarnath Jaihind Co-op Bank	AJHC
SVC Co-op Bank Limited	SVCB
Airtel Payments Bank	AIRP
ESAF Small Finance Bank	ESMF
Fincare Small Finance Bank Limited	FSFB
Emirates NBD Bank (P J S C)	EBIL
Dattatraya Maharaj Kalambe Jaloli Sahakari Bank Ltd.	DMKJ
Fino Payments Bank	FINO
The Navnirman Co-Operative Bank Ltd	NVNM
Surat National Co-Operative Bank Limited	SUNB
The Varachha Co-op Bank Ltd	VARA
Prime Co-operative Bank Ltd.	PMEC
The Surat District Co-op Bank Ltd.	SDCB
BHAGINI NIVEDITA SAHAKARI BANK LTD PUNE	BNSB
ARUNACHAL PRADESH RURAL BANK	ARBL
DURGAPUR STEEL PEOPLES COOP BANK LTD	DURG
Smriti Nagrik Sahakari Bank	SNBK
THE TAMILNADU STATE APEX COOP BANK	TNSC
TELANGANA STATE CO-OP APEX BANK	TSAB
Bassein Catholic Co-op. Bank Ltd.	BACB
BNP Paribas	BNPA
HDFC Bank Limited	HDFC
ICICI Bank Limited	ICIC
NKGSB Co-operative Bank Ltd	NKGS
Punjab National Bank	PUNB
The Dombivli Nagari Sahakari Bank Ltd.	DNSB
The Hong Kong & Shanghai Banking Corporation Ltd.	HSBC
The Nainital Bank ltd	NTBL
Bandhan Bank	BDBL
The Vijay Co-Operative Bank Ltd	VCOB
Jio Payments Bank Limited	JIOP
NORTH EAST SMALL FINANCE BANK LTD	NESF
The Citizen Credit Co-op Bank Ltd	CCBL
Lakshmi Vilas Bank	LAVB
The Gujarat State Co-op Bank Ltd	GSCB
THE AHMEDABAD MERCANTILE CO-OP BANK LTD	AMCB